Inside Macintosh: Telephony /

Chapter 1 - Introduction to Telephony on the Macintosh / Telephone Manager Initialization Reference

Data Structures

Telephone Record

The telephone record describes the capabilities of a particular telephone tool and maintains pointers to internal Telephone Manager data structures. The Telephone Manager uses this information to translate the network-independent routines that your application calls into their equivalent services implemented according to the protocols of a particular telephone terminal. The TELNewWithResult function fill in most of the fields in the telephone record when you create a new telephone record. The telephone record is defined by the TELRecord data type.

Note

To ensure compatibility with future versions of the Telephone Manager, your application should not directly manipulate any fields in the telephone record other than the refCon and userData fields. For most purposes, the Telephone Manager provides all of the functions required to manipulate the relevant fields in the telephone record.

struct TELRecord {
   short                   procID;
   TELFlags                flags;
   short                   reserved;
   long                    refCon;
   long                    userData;
   UniversalProcPtr        defproc;
   Ptr                     config;
   Ptr                     oldConfig;
   TELTermPtr              pTELTerm;
   long                    telPrivate;
   long                    reserved1;
   long                    reserved2;
   long                    pTELTermSize;
   short                   version;
};
typedef struct TELRecord TELRecord;
typedef TELRecord *TELPtr, **TELHandle;

Field Description

procID

The tool ID for a given telephone tool. The value for this field is dynamically generated by the Telephone Manager when your application calls the TELGetProcID function.

flags

A bit field indicating the status of certain terminal specific features. These features are set by a telephone tool in response to the flag bits you set when creating a telephone record. For listing of valid flags, consult "Telephone Record Flags" on page 1-22.

reserved

Reserved for use by the Telephone Manager. You should not use this field in your application.

refCon

A 4-byte field that is available for use by your application and that is ignored by the Telephone Manager.

userData

A 4-byte field that is available for use by your application and that is ignored by the Telephone Manager.

defproc

A pointer to the main code resource of the telephone tool associated with this telephone record.

config

A pointer to a data block that supplies tool specific details such as directory numbers and features associated with a particular telephone terminal. The structure, size, and contents of the configuration block vary depending on how a particular telephone tool is designed.

To manipulate fields in the configuration record, you can use the TELGetConfig and TELSetConfig functions. You can save the current state of the configuration block by storing the configuration string returned by TELGetConfig. You can then restore the state of the configuration by passing the configuration string through the TELSetConfig function.

oldConfig

A pointer to the most recently saved version of the configuration block. Your application is responsible for setting this pointer when the user saves a session document, as described in Inside the Macintosh Communications Toolbox. If necessary, you can use the TELGetConfig and TELSetConfig functions to manipulate these fields.

pTELTerm

A pointer to a telephone terminal record. See "Telephone Terminal Record" on page 2-16.

telPrivate

Reserved for use by the telephone tool.

reserved1

Reserved for the Telephone Manager. You should not use this field in your application.

reserved2

Reserved for the Telephone Manager. You should not use this field in your application.

pTELTermSize

The size (in bytes) of the telephone terminal record pointed to by the pTELTerm field.

version

The latest version of the Telephone Manager for which the current telephone tool is compatible. This value is supplied by the telephone tool when a terminal is opened.